


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Futures (Java) &mdash; Akka Documentation</title>
    
    <link rel="stylesheet" href="../_static/style.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/prettify.css" type="text/css" />
    <link rel="stylesheet" href="../_static/base.css" type="text/css" />
    <link rel="stylesheet" href="../_static/docs.css" type="text/css" />
    <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Exo:300,400,600,700" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '2.0.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/toc.js"></script>
    <script type="text/javascript" src="../_static/prettify.js"></script>
    <script type="text/javascript" src="../_static/highlightCode.js"></script>
    <script type="text/javascript" src="../_static/effects.core.js"></script>
    <script type="text/javascript" src="../_static/effects.highlight.js"></script>
    <script type="text/javascript" src="../_static/scrollTo.js"></script>
    <script type="text/javascript" src="../_static/contentsFix.js"></script>
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="top" title="Akka Documentation" href="../index.html" />
    <link rel="up" title="Java API" href="index.html" />
    <link rel="next" title="Fault Tolerance (Java)" href="fault-tolerance.html" />
    <link rel="prev" title="Scheduler (Java)" href="scheduler.html" /> 
  </head>
  <body>
  <div class="navbar">
    <div class="navbar-inner">
      <div class="container">
        <div class="navbar-logo">
          <a href="http://akka.io"><img src="../_static/logo-small.png" /></a>
        </div>    
        <ul class="nav">
          <li><a href="http://akka.io/docs">Documentation</a></li>
          <li><a href="http://akka.io/downloads">Download</a></li>
          <li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>
          <li><a href="http://github.com/akka/akka">Code</a></li>           
          <li><a href="http://typesafe.com/products/typesafe-subscription">Commerical Support</a></li>
        </ul>
      </div>
    </div>
  </div>
  <div class="main">
    <div class="container">
      <div class="page-title">Futures (Java)</div><div class="pdf-link"><a href="http://akka.io/docs/akka/2.0.1/Akka.pdf"><img src="../_static/pdf-icon.png" style="height: 40px;" /></a></div></div>
    <div class="main-container">
      <div class="container">
        <div class="row">
          <div class="span12">
            <ul class="breadcrumb">           
              <li>
                 <span class="divider">|</span> <a href="fault-tolerance.html">Fault Tolerance (Java)</a> <span class="divider">»</span>
              </li>
              <li>
                <a href="../index.html">Contents</a>
              </li>
              <li>
                <span class="divider">«</span> <a href="scheduler.html">Scheduler (Java)</a> <span class="divider">|</span>
              </li>
              <li>
                Version 2.0.1
              </li>
            </ul>         
          </div>
        </div>
        <div class="row">
          <div class="span9">
            
  <div class="section" id="futures-java">
<span id="id1"></span><h1>Futures (Java)</h1>
<div class="section" id="introduction">
<h2>Introduction</h2>
<p>In Akka, a <a class="reference external" href="http://en.wikipedia.org/wiki/Futures_and_promises">Future</a> is a data structure used
to retrieve the result of some concurrent operation. This operation is usually performed by an <tt class="docutils literal"><span class="pre">Actor</span></tt> or
by the <tt class="docutils literal"><span class="pre">Dispatcher</span></tt> directly. This result can be accessed synchronously (blocking) or asynchronously (non-blocking).</p>
</div>
<div class="section" id="execution-contexts">
<h2>Execution Contexts</h2>
<p>In order to execute callbacks and operations, Futures need something called an <tt class="docutils literal"><span class="pre">ExecutionContext</span></tt>,
which is very similar to a <tt class="docutils literal"><span class="pre">java.util.concurrent.Executor</span></tt>. if you have an <tt class="docutils literal"><span class="pre">ActorSystem</span></tt> in scope,
it will use its default dispatcher as the <tt class="docutils literal"><span class="pre">ExecutionContext</span></tt>, or you can use the factory methods provided
by the <tt class="docutils literal"><span class="pre">ExecutionContexts</span></tt> class to wrap <tt class="docutils literal"><span class="pre">Executors</span></tt> and <tt class="docutils literal"><span class="pre">ExecutorServices</span></tt>, or even create your own.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.dispatch.</span><span class="o">*;</span>
<span class="k">import</span> <span class="nn">akka.util.Timeout</span><span class="o">;</span>

<span class="k">import</span> <span class="nn">akka.dispatch.ExecutionContexts</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.dispatch.ExecutionContextExecutorService</span><span class="o">;</span>

      <span class="nc">ExecutionContextExecutorService</span> <span class="n">ec</span> <span class="k">=</span>
        <span class="nc">ExecutionContexts</span><span class="o">.</span><span class="n">fromExecutorService</span><span class="o">(</span><span class="n">yourExecutorServiceGoesHere</span><span class="o">);</span>

      <span class="c1">//Use ec with your Futures</span>
      <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">f1</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">successful</span><span class="o">(</span><span class="s">&quot;foo&quot;</span><span class="o">,</span> <span class="n">ec</span><span class="o">);</span>

      <span class="c1">// Then you shut the ec down somewhere at the end of your program/application.</span>
      <span class="n">ec</span><span class="o">.</span><span class="n">shutdown</span><span class="o">();</span>
</pre></div>
</div>
</div>
<div class="section" id="use-with-actors">
<h2>Use with Actors</h2>
<p>There are generally two ways of getting a reply from an <tt class="docutils literal"><span class="pre">UntypedActor</span></tt>: the first is by a sent message (<tt class="docutils literal"><span class="pre">actorRef.tell(msg)</span></tt>),
which only works if the original sender was an <tt class="docutils literal"><span class="pre">UntypedActor</span></tt>) and the second is through a <tt class="docutils literal"><span class="pre">Future</span></tt>.</p>
<p>Using the <tt class="docutils literal"><span class="pre">ActorRef</span></tt>&#8216;s <tt class="docutils literal"><span class="pre">ask</span></tt> method to send a message will return a Future.
To wait for and retrieve the actual result the simplest method is:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.dispatch.</span><span class="o">*;</span>
<span class="k">import</span> <span class="nn">akka.util.Timeout</span><span class="o">;</span>

    <span class="nc">Timeout</span> <span class="n">timeout</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">Timeout</span><span class="o">(</span><span class="nc">Duration</span><span class="o">.</span><span class="n">parse</span><span class="o">(</span><span class="s">&quot;5 seconds&quot;</span><span class="o">));</span>
    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;</span> <span class="n">future</span> <span class="k">=</span> <span class="nc">Patterns</span><span class="o">.</span><span class="n">ask</span><span class="o">(</span><span class="n">actor</span><span class="o">,</span> <span class="n">msg</span><span class="o">,</span> <span class="n">timeout</span><span class="o">);</span>
    <span class="nc">String</span> <span class="n">result</span> <span class="k">=</span> <span class="o">(</span><span class="nc">String</span><span class="o">)</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">future</span><span class="o">,</span> <span class="n">timeout</span><span class="o">.</span><span class="n">duration</span><span class="o">());</span>
</pre></div>
</div>
<p>This will cause the current thread to block and wait for the <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> to &#8216;complete&#8217; the <tt class="docutils literal"><span class="pre">Future</span></tt> with it&#8217;s reply.
Blocking is discouraged though as it can cause performance problem.
The blocking operations are located in <tt class="docutils literal"><span class="pre">Await.result</span></tt> and <tt class="docutils literal"><span class="pre">Await.ready</span></tt> to make it easy to spot where blocking occurs.
Alternatives to blocking are discussed further within this documentation.
Also note that the <tt class="docutils literal"><span class="pre">Future</span></tt> returned by an <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> is a <tt class="docutils literal"><span class="pre">Future&lt;Object&gt;</span></tt> since an <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> is dynamic.
That is why the cast to <tt class="docutils literal"><span class="pre">String</span></tt> is used in the above sample.</p>
</div>
<div class="section" id="use-directly">
<h2>Use Directly</h2>
<p>A common use case within Akka is to have some computation performed concurrently without needing
the extra utility of an <tt class="docutils literal"><span class="pre">UntypedActor</span></tt>. If you find yourself creating a pool of <tt class="docutils literal"><span class="pre">UntypedActor</span></tt>s for the sole reason
of performing a calculation in parallel, there is an easier (and faster) way:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.util.Duration</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.japi.Function</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">java.util.concurrent.Callable</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">dispatch</span><span class="o">.</span><span class="nc">Futures</span><span class="o">.</span><span class="n">future</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">static</span> <span class="n">java</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">concurrent</span><span class="o">.</span><span class="nc">TimeUnit</span><span class="o">.</span><span class="nc">SECONDS</span><span class="o">;</span>

    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">f</span> <span class="k">=</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="n">public</span> <span class="nc">String</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
        <span class="k">return</span> <span class="s">&quot;Hello&quot;</span> <span class="o">+</span> <span class="s">&quot;World&quot;</span><span class="o">;</span>
      <span class="o">}</span>
    <span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
    <span class="nc">String</span> <span class="n">result</span> <span class="k">=</span> <span class="o">(</span><span class="nc">String</span><span class="o">)</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">f</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
</pre></div>
</div>
<p>In the above code the block passed to <tt class="docutils literal"><span class="pre">future</span></tt> will be executed by the default <tt class="docutils literal"><span class="pre">Dispatcher</span></tt>,
with the return value of the block used to complete the <tt class="docutils literal"><span class="pre">Future</span></tt> (in this case, the result would be the string: &#8220;HelloWorld&#8221;).
Unlike a <tt class="docutils literal"><span class="pre">Future</span></tt> that is returned from an <tt class="docutils literal"><span class="pre">UntypedActor</span></tt>, this <tt class="docutils literal"><span class="pre">Future</span></tt> is properly typed,
and we also avoid the overhead of managing an <tt class="docutils literal"><span class="pre">UntypedActor</span></tt>.</p>
<p>You can also create already completed Futures using the <tt class="docutils literal"><span class="pre">Futures</span></tt> class, which can be either successes:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">successful</span><span class="o">(</span><span class="s">&quot;Yay!&quot;</span><span class="o">,</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
</pre></div>
</div>
<p>Or failures:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">otherFuture</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">failed</span><span class="o">(</span><span class="k">new</span> <span class="nc">IllegalArgumentException</span><span class="o">(</span><span class="s">&quot;Bang!&quot;</span><span class="o">),</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
</pre></div>
</div>
</div>
<div class="section" id="functional-futures">
<h2>Functional Futures</h2>
<p>Akka&#8217;s <tt class="docutils literal"><span class="pre">Future</span></tt> has several monadic methods that are very similar to the ones used by <tt class="docutils literal"><span class="pre">Scala</span></tt>&#8216;s collections.
These allow you to create &#8216;pipelines&#8217; or &#8216;streams&#8217; that the result will travel through.</p>
<div class="section" id="future-is-a-monad">
<h3>Future is a Monad</h3>
<p>The first method for working with <tt class="docutils literal"><span class="pre">Future</span></tt> functionally is <tt class="docutils literal"><span class="pre">map</span></tt>. This method takes a <tt class="docutils literal"><span class="pre">Mapper</span></tt> which performs
some operation on the result of the <tt class="docutils literal"><span class="pre">Future</span></tt>, and returning a new result.
The return value of the <tt class="docutils literal"><span class="pre">map</span></tt> method is another <tt class="docutils literal"><span class="pre">Future</span></tt> that will contain the new result:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.util.Duration</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.japi.Function</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">java.util.concurrent.Callable</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">dispatch</span><span class="o">.</span><span class="nc">Futures</span><span class="o">.</span><span class="n">future</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">static</span> <span class="n">java</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">concurrent</span><span class="o">.</span><span class="nc">TimeUnit</span><span class="o">.</span><span class="nc">SECONDS</span><span class="o">;</span>

    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">f1</span> <span class="k">=</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="n">public</span> <span class="nc">String</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
        <span class="k">return</span> <span class="s">&quot;Hello&quot;</span> <span class="o">+</span> <span class="s">&quot;World&quot;</span><span class="o">;</span>
      <span class="o">}</span>
    <span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>

    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">f2</span> <span class="k">=</span> <span class="n">f1</span><span class="o">.</span><span class="n">map</span><span class="o">(</span><span class="k">new</span> <span class="nc">Mapper</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">Integer</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="n">public</span> <span class="nc">Integer</span> <span class="n">apply</span><span class="o">(</span><span class="nc">String</span> <span class="n">s</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">s</span><span class="o">.</span><span class="n">length</span><span class="o">();</span>
      <span class="o">}</span>
    <span class="o">});</span>

    <span class="n">int</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">f2</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
    <span class="n">assertEquals</span><span class="o">(</span><span class="mi">10</span><span class="o">,</span> <span class="n">result</span><span class="o">);</span>
</pre></div>
</div>
<p>In this example we are joining two strings together within a Future. Instead of waiting for f1 to complete,
we apply our function that calculates the length of the string using the <tt class="docutils literal"><span class="pre">map</span></tt> method.
Now we have a second Future, f2, that will eventually contain an <tt class="docutils literal"><span class="pre">Integer</span></tt>.
When our original <tt class="docutils literal"><span class="pre">Future</span></tt>, f1, completes, it will also apply our function and complete the second Future
with its result. When we finally <tt class="docutils literal"><span class="pre">get</span></tt> the result, it will contain the number 10.
Our original Future still contains the string &#8220;HelloWorld&#8221; and is unaffected by the <tt class="docutils literal"><span class="pre">map</span></tt>.</p>
<p>Something to note when using these methods: if the <tt class="docutils literal"><span class="pre">Future</span></tt> is still being processed when one of these methods are called,
it will be the completing thread that actually does the work.
If the <tt class="docutils literal"><span class="pre">Future</span></tt> is already complete though, it will be run in our current thread. For example:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">f1</span> <span class="k">=</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">String</span> <span class="n">call</span><span class="o">()</span> <span class="n">throws</span> <span class="nc">Exception</span> <span class="o">{</span>
    <span class="nc">Thread</span><span class="o">.</span><span class="n">sleep</span><span class="o">(</span><span class="mi">100</span><span class="o">);</span>
    <span class="k">return</span> <span class="s">&quot;Hello&quot;</span> <span class="o">+</span> <span class="s">&quot;World&quot;</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>

<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">f2</span> <span class="k">=</span> <span class="n">f1</span><span class="o">.</span><span class="n">map</span><span class="o">(</span><span class="k">new</span> <span class="nc">Mapper</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">Integer</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Integer</span> <span class="n">apply</span><span class="o">(</span><span class="nc">String</span> <span class="n">s</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">return</span> <span class="n">s</span><span class="o">.</span><span class="n">length</span><span class="o">();</span>
  <span class="o">}</span>
<span class="o">});</span>
</pre></div>
</div>
<p>The original <tt class="docutils literal"><span class="pre">Future</span></tt> will take at least 0.1 second to execute now, which means it is still being processed at
the time we call <tt class="docutils literal"><span class="pre">map</span></tt>. The function we provide gets stored within the <tt class="docutils literal"><span class="pre">Future</span></tt> and later executed automatically
by the dispatcher when the result is ready.</p>
<p>If we do the opposite:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">f1</span> <span class="k">=</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">String</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="s">&quot;Hello&quot;</span> <span class="o">+</span> <span class="s">&quot;World&quot;</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>

<span class="nc">Thread</span><span class="o">.</span><span class="n">sleep</span><span class="o">(</span><span class="mi">100</span><span class="o">);</span>

<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">f2</span> <span class="k">=</span> <span class="n">f1</span><span class="o">.</span><span class="n">map</span><span class="o">(</span><span class="k">new</span> <span class="nc">Mapper</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">Integer</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Integer</span> <span class="n">apply</span><span class="o">(</span><span class="nc">String</span> <span class="n">s</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">return</span> <span class="n">s</span><span class="o">.</span><span class="n">length</span><span class="o">();</span>
  <span class="o">}</span>
<span class="o">});</span>
</pre></div>
</div>
<p>Our little string has been processed long before our 0.1 second sleep has finished. Because of this,
the dispatcher has moved onto other messages that need processing and can no longer calculate
the length of the string for us, instead it gets calculated in the current thread just as if we weren&#8217;t using a <tt class="docutils literal"><span class="pre">Future</span></tt>.</p>
<p>Normally this works quite well as it means there is very little overhead to running a quick function.
If there is a possibility of the function taking a non-trivial amount of time to process it might be better
to have this done concurrently, and for that we use <tt class="docutils literal"><span class="pre">flatMap</span></tt>:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">f1</span> <span class="k">=</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">String</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="s">&quot;Hello&quot;</span> <span class="o">+</span> <span class="s">&quot;World&quot;</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>

<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">f2</span> <span class="k">=</span> <span class="n">f1</span><span class="o">.</span><span class="n">flatMap</span><span class="o">(</span><span class="k">new</span> <span class="nc">Mapper</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">apply</span><span class="o">(</span><span class="k">final</span> <span class="nc">String</span> <span class="n">s</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">return</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="n">public</span> <span class="nc">Integer</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">s</span><span class="o">.</span><span class="n">length</span><span class="o">();</span>
      <span class="o">}</span>
    <span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
  <span class="o">}</span>
<span class="o">});</span>
</pre></div>
</div>
<p>Now our second Future is executed concurrently as well. This technique can also be used to combine the results
of several Futures into a single calculation, which will be better explained in the following sections.</p>
<p>If you need to do conditional propagation, you can use <tt class="docutils literal"><span class="pre">filter</span></tt>:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">future1</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">successful</span><span class="o">(</span><span class="mi">4</span><span class="o">,</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">successfulFilter</span> <span class="k">=</span> <span class="n">future1</span><span class="o">.</span><span class="n">filter</span><span class="o">(</span><span class="nc">Filter</span><span class="o">.</span><span class="n">filterOf</span><span class="o">(</span><span class="k">new</span> <span class="nc">Function</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">,</span> <span class="nc">Boolean</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Boolean</span> <span class="n">apply</span><span class="o">(</span><span class="nc">Integer</span> <span class="n">i</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">return</span> <span class="n">i</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">}));</span>

<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">failedFilter</span> <span class="k">=</span> <span class="n">future1</span><span class="o">.</span><span class="n">filter</span><span class="o">(</span><span class="nc">Filter</span><span class="o">.</span><span class="n">filterOf</span><span class="o">(</span><span class="k">new</span> <span class="nc">Function</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">,</span> <span class="nc">Boolean</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Boolean</span> <span class="n">apply</span><span class="o">(</span><span class="nc">Integer</span> <span class="n">i</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">return</span> <span class="n">i</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">!=</span> <span class="mi">0</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">}));</span>
<span class="c1">//When filter fails, the returned Future will be failed with a scala.MatchError</span>
</pre></div>
</div>
</div>
<div class="section" id="composing-futures">
<h3>Composing Futures</h3>
<p>It is very often desirable to be able to combine different Futures with each other,
below are some examples on how that can be done in a non-blocking fashion.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">dispatch</span><span class="o">.</span><span class="nc">Futures</span><span class="o">.</span><span class="n">sequence</span><span class="o">;</span>

    <span class="c1">//Some source generating a sequence of Future&lt;Integer&gt;:s</span>
    <span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;&gt;</span> <span class="n">listOfFutureInts</span> <span class="k">=</span> <span class="n">source</span><span class="o">;</span>

    <span class="c1">// now we have a Future[Iterable[Integer]]</span>
    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;&gt;</span> <span class="n">futureListOfInts</span> <span class="k">=</span> <span class="n">sequence</span><span class="o">(</span><span class="n">listOfFutureInts</span><span class="o">,</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>

    <span class="c1">// Find the sum of the odd numbers</span>
    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Long</span><span class="o">&gt;</span> <span class="n">futureSum</span> <span class="k">=</span> <span class="n">futureListOfInts</span><span class="o">.</span><span class="n">map</span><span class="o">(</span><span class="k">new</span> <span class="nc">Mapper</span><span class="o">&lt;</span><span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;,</span> <span class="nc">Long</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="n">public</span> <span class="nc">Long</span> <span class="n">apply</span><span class="o">(</span><span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">ints</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">long</span> <span class="n">sum</span> <span class="k">=</span> <span class="mi">0</span><span class="o">;</span>
        <span class="k">for</span> <span class="o">(</span><span class="nc">Integer</span> <span class="n">i</span> <span class="k">:</span> <span class="kt">ints</span><span class="o">)</span>
          <span class="n">sum</span> <span class="o">+=</span> <span class="n">i</span><span class="o">;</span>
        <span class="k">return</span> <span class="n">sum</span><span class="o">;</span>
      <span class="o">}</span>
    <span class="o">});</span>

    <span class="n">long</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">futureSum</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
</pre></div>
</div>
<p>To better explain what happened in the example, <tt class="docutils literal"><span class="pre">Future.sequence</span></tt> is taking the <tt class="docutils literal"><span class="pre">Iterable&lt;Future&lt;Integer&gt;&gt;</span></tt>
and turning it into a <tt class="docutils literal"><span class="pre">Future&lt;Iterable&lt;Integer&gt;&gt;</span></tt>. We can then use <tt class="docutils literal"><span class="pre">map</span></tt> to work with the <tt class="docutils literal"><span class="pre">Iterable&lt;Integer&gt;</span></tt> directly,
and we aggregate the sum of the <tt class="docutils literal"><span class="pre">Iterable</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">traverse</span></tt> method is similar to <tt class="docutils literal"><span class="pre">sequence</span></tt>, but it takes a sequence of <tt class="docutils literal"><span class="pre">A``s</span> <span class="pre">and</span> <span class="pre">applies</span> <span class="pre">a</span> <span class="pre">function</span> <span class="pre">from</span> <span class="pre">``A</span></tt> to <tt class="docutils literal"><span class="pre">Future&lt;B&gt;</span></tt>
and returns a <tt class="docutils literal"><span class="pre">Future&lt;Iterable&lt;B&gt;&gt;</span></tt>, enabling parallel <tt class="docutils literal"><span class="pre">map</span></tt> over the sequence, if you use <tt class="docutils literal"><span class="pre">Futures.future</span></tt> to create the <tt class="docutils literal"><span class="pre">Future</span></tt>.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">dispatch</span><span class="o">.</span><span class="nc">Futures</span><span class="o">.</span><span class="n">traverse</span><span class="o">;</span>

    <span class="c1">//Just a sequence of Strings</span>
    <span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">listStrings</span> <span class="k">=</span> <span class="nc">Arrays</span><span class="o">.</span><span class="n">asList</span><span class="o">(</span><span class="s">&quot;a&quot;</span><span class="o">,</span> <span class="s">&quot;b&quot;</span><span class="o">,</span> <span class="s">&quot;c&quot;</span><span class="o">);</span>

    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;&gt;</span> <span class="n">futureResult</span> <span class="k">=</span> <span class="n">traverse</span><span class="o">(</span><span class="n">listStrings</span><span class="o">,</span> <span class="k">new</span> <span class="nc">Function</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;&gt;()</span> <span class="o">{</span>
      <span class="n">public</span> <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">apply</span><span class="o">(</span><span class="k">final</span> <span class="nc">String</span> <span class="n">r</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
          <span class="n">public</span> <span class="nc">String</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
            <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">toUpperCase</span><span class="o">();</span>
          <span class="o">}</span>
        <span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
      <span class="o">}</span>
    <span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>

    <span class="c1">//Returns the sequence of strings as upper case</span>
    <span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">futureResult</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
    <span class="n">assertEquals</span><span class="o">(</span><span class="nc">Arrays</span><span class="o">.</span><span class="n">asList</span><span class="o">(</span><span class="s">&quot;A&quot;</span><span class="o">,</span> <span class="s">&quot;B&quot;</span><span class="o">,</span> <span class="s">&quot;C&quot;</span><span class="o">),</span> <span class="n">result</span><span class="o">);</span>
</pre></div>
</div>
<p>It&#8217;s as simple as that!</p>
<p>Then there&#8217;s a method that&#8217;s called <tt class="docutils literal"><span class="pre">fold</span></tt> that takes a start-value,
a sequence of <tt class="docutils literal"><span class="pre">Future</span></tt>:s and a function from the type of the start-value, a timeout,
and the type of the futures and returns something with the same type as the start-value,
and then applies the function to all elements in the sequence of futures, non-blockingly,
the execution will be started when the last of the Futures is completed.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.japi.Function2</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">dispatch</span><span class="o">.</span><span class="nc">Futures</span><span class="o">.</span><span class="n">fold</span><span class="o">;</span>


    <span class="c1">//A sequence of Futures, in this case Strings</span>
    <span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;&gt;</span> <span class="n">futures</span> <span class="k">=</span> <span class="n">source</span><span class="o">;</span>

    <span class="c1">//Start value is the empty string</span>
    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">resultFuture</span> <span class="k">=</span> <span class="n">fold</span><span class="o">(</span><span class="s">&quot;&quot;</span><span class="o">,</span> <span class="n">futures</span><span class="o">,</span> <span class="k">new</span> <span class="nc">Function2</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">String</span><span class="o">,</span> <span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="n">public</span> <span class="nc">String</span> <span class="n">apply</span><span class="o">(</span><span class="nc">String</span> <span class="n">r</span><span class="o">,</span> <span class="nc">String</span> <span class="n">t</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">r</span> <span class="o">+</span> <span class="n">t</span><span class="o">;</span> <span class="c1">//Just concatenate</span>
      <span class="o">}</span>
    <span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
    <span class="nc">String</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">resultFuture</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
</pre></div>
</div>
<p>That&#8217;s all it takes!</p>
<p>If the sequence passed to <tt class="docutils literal"><span class="pre">fold</span></tt> is empty, it will return the start-value, in the case above, that will be empty String.
In some cases you don&#8217;t have a start-value and you&#8217;re able to use the value of the first completing Future
in the sequence as the start-value, you can use <tt class="docutils literal"><span class="pre">reduce</span></tt>, it works like this:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">dispatch</span><span class="o">.</span><span class="nc">Futures</span><span class="o">.</span><span class="n">reduce</span><span class="o">;</span>


    <span class="c1">//A sequence of Futures, in this case Strings</span>
    <span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;&gt;</span> <span class="n">futures</span> <span class="k">=</span> <span class="n">source</span><span class="o">;</span>

    <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;</span> <span class="n">resultFuture</span> <span class="k">=</span> <span class="n">reduce</span><span class="o">(</span><span class="n">futures</span><span class="o">,</span> <span class="k">new</span> <span class="nc">Function2</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">,</span> <span class="nc">String</span><span class="o">,</span> <span class="nc">Object</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="n">public</span> <span class="nc">Object</span> <span class="n">apply</span><span class="o">(</span><span class="nc">Object</span> <span class="n">r</span><span class="o">,</span> <span class="nc">String</span> <span class="n">t</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">r</span> <span class="o">+</span> <span class="n">t</span><span class="o">;</span> <span class="c1">//Just concatenate</span>
      <span class="o">}</span>
    <span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>

    <span class="nc">Object</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">resultFuture</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
</pre></div>
</div>
<p>Same as with <tt class="docutils literal"><span class="pre">fold</span></tt>, the execution will be started when the last of the Futures is completed, you can also parallelize
it by chunking your futures into sub-sequences and reduce them, and then reduce the reduced results again.</p>
<p>This is just a sample of what can be done.</p>
</div>
</div>
<div class="section" id="callbacks">
<h2>Callbacks</h2>
<p>Sometimes you just want to listen to a <tt class="docutils literal"><span class="pre">Future</span></tt> being completed, and react to that not by creating a new Future, but by side-effecting.
For this Akka supports <tt class="docutils literal"><span class="pre">onComplete</span></tt>, <tt class="docutils literal"><span class="pre">onSuccess</span></tt> and <tt class="docutils literal"><span class="pre">onFailure</span></tt>, of which the latter two are specializations of the first.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">future</span><span class="o">.</span><span class="n">onSuccess</span><span class="o">(</span><span class="k">new</span> <span class="nc">OnSuccess</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="n">void</span> <span class="n">onSuccess</span><span class="o">(</span><span class="nc">String</span> <span class="n">result</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="s">&quot;bar&quot;</span> <span class="o">==</span> <span class="n">result</span><span class="o">)</span> <span class="o">{</span>
      <span class="c1">//Do something if it resulted in &quot;bar&quot;</span>
    <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
      <span class="c1">//Do something if it was some other String</span>
    <span class="o">}</span>
  <span class="o">}</span>
<span class="o">});</span>
</pre></div>
</div>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">future</span><span class="o">.</span><span class="n">onFailure</span><span class="o">(</span><span class="k">new</span> <span class="nc">OnFailure</span><span class="o">()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="n">void</span> <span class="n">onFailure</span><span class="o">(</span><span class="nc">Throwable</span> <span class="n">failure</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="n">failure</span> <span class="n">instanceof</span> <span class="nc">IllegalStateException</span><span class="o">)</span> <span class="o">{</span>
      <span class="c1">//Do something if it was this particular failure</span>
    <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
      <span class="c1">//Do something if it was some other failure</span>
    <span class="o">}</span>
  <span class="o">}</span>
<span class="o">});</span>
</pre></div>
</div>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">future</span><span class="o">.</span><span class="n">onComplete</span><span class="o">(</span><span class="k">new</span> <span class="nc">OnComplete</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
    <span class="n">public</span> <span class="n">void</span> <span class="n">onComplete</span><span class="o">(</span><span class="nc">Throwable</span> <span class="n">failure</span><span class="o">,</span> <span class="nc">String</span> <span class="n">result</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">if</span> <span class="o">(</span><span class="n">failure</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
            <span class="c1">//We got a failure, handle it here</span>
        <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
            <span class="c1">// We got a result, do something with it</span>
        <span class="o">}</span>
    <span class="o">}</span>
<span class="o">});</span>
</pre></div>
</div>
</div>
<div class="section" id="ordering">
<h2>Ordering</h2>
<p>Since callbacks are executed in any order and potentially in parallel,
it can be tricky at the times when you need sequential ordering of operations.
But there&#8217;s a solution! And it&#8217;s name is <tt class="docutils literal"><span class="pre">andThen</span></tt>, and it creates a new Future with
the specified callback, a Future that will have the same result as the Future it&#8217;s called on,
which allows for ordering like in the following sample:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future1</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">successful</span><span class="o">(</span><span class="s">&quot;value&quot;</span><span class="o">,</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">()).</span><span class="n">andThen</span><span class="o">(</span><span class="k">new</span> <span class="nc">OnComplete</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
    <span class="n">public</span> <span class="n">void</span> <span class="n">onComplete</span><span class="o">(</span><span class="nc">Throwable</span> <span class="n">failure</span><span class="o">,</span> <span class="nc">String</span> <span class="n">result</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">if</span> <span class="o">(</span><span class="n">failure</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span>
            <span class="n">sendToIssueTracker</span><span class="o">(</span><span class="n">failure</span><span class="o">);</span>
    <span class="o">}</span>
<span class="o">}).</span><span class="n">andThen</span><span class="o">(</span><span class="k">new</span> <span class="nc">OnComplete</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="n">void</span> <span class="n">onComplete</span><span class="o">(</span><span class="nc">Throwable</span> <span class="n">failure</span><span class="o">,</span> <span class="nc">String</span> <span class="n">result</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="n">result</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span>
      <span class="n">sendToTheInternetz</span><span class="o">(</span><span class="n">result</span><span class="o">);</span>
  <span class="o">}</span>
<span class="o">});</span>
</pre></div>
</div>
</div>
<div class="section" id="auxiliary-methods">
<h2>Auxiliary methods</h2>
<p><tt class="docutils literal"><span class="pre">Future</span></tt> <tt class="docutils literal"><span class="pre">fallbackTo</span></tt> combines 2 Futures into a new <tt class="docutils literal"><span class="pre">Future</span></tt>, and will hold the successful value of the second <tt class="docutils literal"><span class="pre">Future</span></tt>
if the first <tt class="docutils literal"><span class="pre">Future</span></tt> fails.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future1</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">failed</span><span class="o">(</span><span class="k">new</span> <span class="nc">IllegalStateException</span><span class="o">(</span><span class="s">&quot;OHNOES1&quot;</span><span class="o">),</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future2</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">failed</span><span class="o">(</span><span class="k">new</span> <span class="nc">IllegalStateException</span><span class="o">(</span><span class="s">&quot;OHNOES2&quot;</span><span class="o">),</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future3</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">successful</span><span class="o">(</span><span class="s">&quot;bar&quot;</span><span class="o">,</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future4</span> <span class="k">=</span> <span class="n">future1</span><span class="o">.</span><span class="n">fallbackTo</span><span class="o">(</span><span class="n">future2</span><span class="o">).</span><span class="n">fallbackTo</span><span class="o">(</span><span class="n">future3</span><span class="o">);</span> <span class="c1">// Will have &quot;bar&quot; in this case</span>
<span class="nc">String</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">future4</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
<span class="n">assertEquals</span><span class="o">(</span><span class="s">&quot;bar&quot;</span><span class="o">,</span> <span class="n">result</span><span class="o">);</span>
</pre></div>
</div>
<p>You can also combine two Futures into a new <tt class="docutils literal"><span class="pre">Future</span></tt> that will hold a tuple of the two Futures successful results,
using the <tt class="docutils literal"><span class="pre">zip</span></tt> operation.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future1</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">successful</span><span class="o">(</span><span class="s">&quot;foo&quot;</span><span class="o">,</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future2</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">successful</span><span class="o">(</span><span class="s">&quot;bar&quot;</span><span class="o">,</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
<span class="nc">Future</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">future3</span> <span class="k">=</span> <span class="n">future1</span><span class="o">.</span><span class="n">zip</span><span class="o">(</span><span class="n">future2</span><span class="o">).</span><span class="n">map</span><span class="o">(</span><span class="k">new</span> <span class="nc">Mapper</span><span class="o">&lt;</span><span class="n">scala</span><span class="o">.</span><span class="nc">Tuple2</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">String</span><span class="o">&gt;,</span> <span class="nc">String</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">String</span> <span class="n">apply</span><span class="o">(</span><span class="n">scala</span><span class="o">.</span><span class="nc">Tuple2</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">String</span><span class="o">&gt;</span> <span class="n">zipped</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">return</span> <span class="n">zipped</span><span class="o">.</span><span class="n">_1</span><span class="o">()</span> <span class="o">+</span> <span class="s">&quot; &quot;</span> <span class="o">+</span> <span class="n">zipped</span><span class="o">.</span><span class="n">_2</span><span class="o">();</span>
  <span class="o">}</span>
<span class="o">});</span>

<span class="nc">String</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">future3</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
<span class="n">assertEquals</span><span class="o">(</span><span class="s">&quot;foo bar&quot;</span><span class="o">,</span> <span class="n">result</span><span class="o">);</span>
</pre></div>
</div>
</div>
<div class="section" id="exceptions">
<h2>Exceptions</h2>
<p>Since the result of a <tt class="docutils literal"><span class="pre">Future</span></tt> is created concurrently to the rest of the program, exceptions must be handled differently.
It doesn&#8217;t matter if an <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> or the dispatcher is completing the <tt class="docutils literal"><span class="pre">Future</span></tt>, if an <tt class="docutils literal"><span class="pre">Exception</span></tt> is caught
the <tt class="docutils literal"><span class="pre">Future</span></tt> will contain it instead of a valid result. If a <tt class="docutils literal"><span class="pre">Future</span></tt> does contain an <tt class="docutils literal"><span class="pre">Exception</span></tt>,
calling <tt class="docutils literal"><span class="pre">Await.result</span></tt> will cause it to be thrown again so it can be handled properly.</p>
<p>It is also possible to handle an <tt class="docutils literal"><span class="pre">Exception</span></tt> by returning a different result.
This is done with the <tt class="docutils literal"><span class="pre">recover</span></tt> method. For example:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">future</span> <span class="k">=</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Integer</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="mi">1</span> <span class="o">/</span> <span class="mi">0</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">()).</span><span class="n">recover</span><span class="o">(</span><span class="k">new</span> <span class="nc">Recover</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Integer</span> <span class="n">recover</span><span class="o">(</span><span class="nc">Throwable</span> <span class="n">problem</span><span class="o">)</span> <span class="n">throws</span> <span class="nc">Throwable</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="n">problem</span> <span class="n">instanceof</span> <span class="nc">ArithmeticException</span><span class="o">)</span>
      <span class="k">return</span> <span class="mi">0</span><span class="o">;</span>
    <span class="k">else</span>
      <span class="k">throw</span> <span class="n">problem</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">});</span>
<span class="n">int</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">future</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
<span class="n">assertEquals</span><span class="o">(</span><span class="n">result</span><span class="o">,</span> <span class="mi">0</span><span class="o">);</span>
</pre></div>
</div>
<p>In this example, if the actor replied with a <tt class="docutils literal"><span class="pre">akka.actor.Status.Failure</span></tt> containing the <tt class="docutils literal"><span class="pre">ArithmeticException</span></tt>,
our <tt class="docutils literal"><span class="pre">Future</span></tt> would have a result of 0. The <tt class="docutils literal"><span class="pre">recover</span></tt> method works very similarly to the standard try/catch blocks,
so multiple <tt class="docutils literal"><span class="pre">Exception</span></tt>s can be handled in this manner, and if an <tt class="docutils literal"><span class="pre">Exception</span></tt> is not handled this way
it will behave as if we hadn&#8217;t used the <tt class="docutils literal"><span class="pre">recover</span></tt> method.</p>
<p>You can also use the <tt class="docutils literal"><span class="pre">recoverWith</span></tt> method, which has the same relationship to <tt class="docutils literal"><span class="pre">recover</span></tt> as <tt class="docutils literal"><span class="pre">flatMap</span></tt> has to <tt class="docutils literal"><span class="pre">map</span></tt>,
and is use like this:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">future</span> <span class="k">=</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Integer</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="mi">1</span> <span class="o">/</span> <span class="mi">0</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">()).</span><span class="n">recoverWith</span><span class="o">(</span><span class="k">new</span> <span class="nc">Recover</span><span class="o">&lt;</span><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="n">recover</span><span class="o">(</span><span class="nc">Throwable</span> <span class="n">problem</span><span class="o">)</span> <span class="n">throws</span> <span class="nc">Throwable</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="n">problem</span> <span class="n">instanceof</span> <span class="nc">ArithmeticException</span><span class="o">)</span> <span class="o">{</span>
      <span class="k">return</span> <span class="n">future</span><span class="o">(</span><span class="k">new</span> <span class="nc">Callable</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;()</span> <span class="o">{</span>
        <span class="n">public</span> <span class="nc">Integer</span> <span class="n">call</span><span class="o">()</span> <span class="o">{</span>
          <span class="k">return</span> <span class="mi">0</span><span class="o">;</span>
        <span class="o">}</span>
      <span class="o">},</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>
    <span class="o">}</span> <span class="k">else</span>
      <span class="k">throw</span> <span class="n">problem</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">});</span>
<span class="n">int</span> <span class="n">result</span> <span class="k">=</span> <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">future</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="nc">SECONDS</span><span class="o">));</span>
<span class="n">assertEquals</span><span class="o">(</span><span class="n">result</span><span class="o">,</span> <span class="mi">0</span><span class="o">);</span>
</pre></div>
</div>
</div>
</div>


          </div>
          <div class="span3"><p class="contents-title">Contents</p>
              <div id="scroller-anchor">
                <div id="scroller">
                  <div id="toc"></div>
                </div>
              </div></div>
        </div>
      </div>
    </div>
  </div>
  <div class="footer">
  <div class="container">
    <ul>
      <li><h5>Akka</h5></li>
      <li><a href="http://akka.io/docs">Documentation</a></li>
      <li><a href="http://akka.io/downloads">Downloads</a></li>
    </ul>
    <ul>
      <li><h5>Contribute</h5></li>
      <li><a href="http://github.com/akka/akka">Source Code</a></li>
      <li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>      
      <li><a href="http://www.assembla.com/spaces/akka/tickets">Report a Bug</a></li>      
    </ul>
    <ul>
      <li><h5>Company</h5></li>
      <li><a href="http://typesafe.com/products/typesafe-subscription">Commercial Support</a></li>
      <li><a href="http://akka.io/team">Team</a></li>
      <li><a href="mailto:info@typesafe.com">Contact</a></li>
    </ul>
    <ul>
      <li><img src="../_static/watermark.png" align="center"/></li>
    </ul>
  </div>
  <div class="container copyright">
    <p style="float: left;">
      © 2012 <a href="http://typesafe.com/">Typesafe Inc.</a> <span class="license">Akka is Open Source and available under the Apache 2 License.</span>
    </p>
    <p style="float: right; font-size: 12px;">
      Last updated: Apr 13, 2012
    </p>          
  </div>
</div>
<script type="text/javascript">
  $('#toc').toc();
</script>
  

  </body>
</html>